Managing Data Handler Components15

Your data handler component provides a number of functions that applications can use to manage their connections to your handler. The most important among these is DataHTask , which provides processor time to your handler. Applications should call this function often so that your handler has enough time to do its work.

Applications may call your handler's DataHPlaybackHints function in order to provide you with some guidelines about how those applications play to use the current data reference.

The DataHFlushData and DataHFlushCache functions allow applications to influence how your component manages its stored data.

DataHTask

Client programs call your component's DataHTask function in order to cede processor time to your data handler.



 
pascal ComponentResult DataHTask (DataHandler dh);

dh: Identifies the calling program's connection to your data handler component.

DISCUSSION

This function is essentially analogous to the Movie Toolbox's MoviesTask function. Client programs call this function in order to give your data handler component time to do its work. Your data handler uses this time to do its work. Because client programs will call this function frequently, and especially so during movie playback or capture, your data handler should return control quickly to the client program.

DataHFlushCache

Your component discards the contents of any cached read buffers.



 
pascal ComponentResult DataHFlushCache (DataHandler dh);

dh: Identifies the calling program's connection to your data handler component.

DISCUSSION

Client programs may call this function if they have, in some way, changed the container associated with the current data reference on their own. Under these circumstances, data your component may have read and cached in anticipation of future read requests from the client may be invalid.

Note that this function does not invalidate any queued read requests (made by calling your component's DataHScheduleData function).

DataHFlushData

Your component forces any data in its write buffers to be written to the device that contains the current data reference.



 
pascal ComponentResult DataHFlushData (DataHandler dh);

dh: Identifies the calling program's connection to your data handler component.

DISCUSSION

This function is essentially analogous to the File Manager's PBFlushFile function. The client program may call this function after any write operation (either DataHPutData or DataHWrite ). Your component should do what is necessary to make sure that the data is written to the storage device that contains the current data reference.

DataHPlaybackHints

The DataHPlaybackHints function allows the client program to provide additional information to your component that you may use to optimize the operation of your data handler.



 
pascal ComponentResult DataHPlaybackHints (

                     DataHandler dh,

                     long flags,

                     unsigned long minFileOffset,

                     unsigned long maxFileOffset,

                     long bytesPerSecond);

dh: Identifies the calling program's connection to your data handler component.
flags: Reserved for use by Apple Computer, Inc. Client programs should always set this parameter to 0.
minFileOffset: Together with the maxFileOffset parameter, specifies the range of data the client program anticipates using from the current data reference. This parameter specifies the earliest byte the program expects to use (that is, the minimum container offset value). If the client expects to access bytes from the beginning of the container, it should set this parameter to 0.
maxFileOffset: Specifies the latest byte the program expects to use (that is, the maximum container offset value). If the client expects to use bytes throughout the container, the client should set this parameter to -1.
bytesPerSecond: Indicates the rate at which your data handler must read data from the data reference in order to keep up with the client program's anticipated needs.

DISCUSSION

Your component should be prepared to have this function called more than once for a given data reference. For example, the Movie Toolbox calls this function whenever a movie's playback rate changes. This is a handy way for your data handler to track playback rate changes.